Programming in Cobra

[gourD]

But that doesn't change my suggestion because if I ask you "gourD, what hierarchical structure do you want to see in the PDF book?" then you have to type this somewhere...And whether you do that type that in the forums, email or the wiki is largely irrelevant in the short run.

I understood your point, but it requires some time. Moreover, maybe it's not just question of just typing few chapter/section titles.

Unless you're so allergic to the trac wiki you won't ever use it all. I realize using it might require an adjustment to your mental model.

It's true that in general I do not like wikis, iow. nothing specifically against Trac.

I also showed that majority of programming language's docs which somehow 'compete' with Cobra do not use wikis as their main source of documentation, but when I find enough time - probaly nothing before Friday - I'll think about it and try to write few chapter/section titles, but not in the mood to spend significant time writing wiki doc online.

[gourD]

I'll think about it and try to write few chapter/section titles, but not in the mood to spend significant time writing wiki doc online.

I had some chat with Charles today and I can see that, for whatever, reason he really like wikis...

Still, as promised, I'll try to put together some structural proposal for the 'new' docs.

However, looking at Documentation page, shows some inconsistencies:

* Overview section has 4 links - one is for presentation in PDF, the remaining 3 are not editable wiki pages
* Code section is two subsections:

** How To section which is not editable and contains 31 links - none of which is editable wiki pages
** Samples section - non-editable itself with a 15 links - nothing is available for edit

* Learning sections has 4 links - 3 of them are not editable wiki page and only Language topic is editable
* Other section - 5 links - Acknowledgements & Other Cobras are non-editable, one link to wikipedia, Release Notes (wiki page) and link to Wiki itself

So, most of the stuff from the Documentation page is not editable?

I know, Charles told me it is due to performance reasons that those pages are made static, but then comparison with e.g. Haskell's wiki (mentioned by him in chat) does not make much sense.

I'm going to work further and update this post as I go along before creating some 'fake' wiki page with proposed structure...

[hopscc]

The reason for a lot of that is historical as the majority of the cobra detail doc info moved from reposing in HTML doc pages to the wiki pages
- Chuck did a lot of the doc, overview and familarisation pages early on as static HTMl pages.
As the wiki doc extended I/we wanted to reference the same content (perhaps via different paths) and so access some of those pages to either provide for items that had not been wiki-docced or to provide links to extra info for completeness/background/etc
( e.g Earlier if you came directly to the wiki pages you wouldnt ever see (or get back to) a lot of the other 'doc'/'background' pages)

The easiest/fastest route was to just link to them from the wiki...
Its only an issue for anyone who wants to edit the (static) pages/modify the content... (doc writers/modifiers)

... for anyone reading any of the documentation pages, whether its implemented as wiki or as HTML doc pages ( or PDf or Slides or videos,images) should be irrelevant - all they should have to do is read the pages/follow the links...

[gourD]

Its only an issue for anyone who wants to edit the (static) pages/modify the content... (doc writers/modifiers)

I wonder how do you find writing doc in browser's edit box convenient in comparison with doing it offline using preferred editor, keeping stuff under (D)VCS etc.

[hopscc]

Editing/minor tweaks are quick and easily doable in the editbox.
Larger ones suck of course so I dont do that .

Bigger chunks/whole sections to start I do offline (I had a template somewhere) generate rough layout for seed content and
cut and paste into the edit box.

The main thing the trac gives is an immediate preview so you can see exactly what the result will look like..
so iterate previews and trac edits till get appearance desired and submit the result...

Havent needed any sort of VCS for this since not have multiple concurrent competing writers and not treading on each other...
After the initial seed content section edits have tended to be minor ( for better or worse)...

The wiki pages are actually versioned in trac ( see History button when editing ) so can view changes between any versions...
but havent had to use that either... ( follow step changes with the wiki Timeline page...).

If I was doing only wiki doc gen I might set it up differently but I tend to do doc when I'm either bored with doing coding/devt, spot a mistake or an annoying omission, someone identifies a lack or I feel like a change - any such are small quanta chunks that fit into gaps...
- for me its a a low-priority background activity with occasional priority inversion....

[gourD]

Editing/minor tweaks are quick and easily doable in the editbox.
Larger ones suck of course so I dont do that .

This sound as good usability pattern.

Bigger chunks/whole sections to start I do offline (I had a template somewhere) generate rough layout for seed content and
cut and paste into the edit box.

Why not keeping them under VCS and using normal developer tools?

The main thing the trac gives is an immediate preview so you can see exactly what the result will look like..
so iterate previews and trac edits till get appearance desired and submit the result...

Bitbucket would also allow you to even edit online, keep it under repo, have WYSIWYG editor (similar or better than Trac) and have preview.

Havent needed any sort of VCS for this since not have multiple concurrent competing writers and not treading on each other...
After the initial seed content section edits have tended to be minor ( for better or worse)...

Yeah, I went through all the wiki pages and noted that in last 12 months there are 12 contributors:

[*] Charles
[*] hopscc
[*] jaegs
[*] Nefarel
[*] nerdzero
[*] torial
[*] todd.a
[*] pyros2097 (minor edits)
[*] hack.augusto (minor edits)
[*] BOOMER - single sublimetext2-related edit, but it looks he disappeared afterwards
[*] mattstraw (minor edits, but could not find him in members list)
[*] kobi7 (minor edits) - not sure if he is still active

So, we can say there are less than 10 contributors and the amount of contribution differs greatly.

Moreover, lot of docs are old and not changing much...

The wiki pages are actually versioned in trac ( see History button when editing ) so can view changes between any versions...
but havent had to use that either... ( follow step changes with the wiki Timeline page...).

It sounds similar to keeping one's documents in version1, version2,...,versionXYZ folders instead of using real VCS.

So, why do you stick with this incomprehensible workflow, having so many hyperlinks not improving the navigation of the docs, but just the contrary etc. instead of working to have decent tutorial, language reference, library reference etc. as it's very common for so many projects is really beyond me.

[Charles]

So, why do you stick with this incomprehensible workflow, having so many hyperlinks not improving the navigation of the docs, but just the contrary etc. instead of working to have decent tutorial, language reference, library reference etc. as it's very common for so many projects is really beyond me.

Making wiki pages is not incomprehensible. I don't know why you think it is. I just made a wiki page today. It was easy.

You are wrong that having hyperlinks does not improve the navigation. That's the very thing that hyperlinks are for and improve!

I don't work much on the docs because I'm busy on the compiler. But docs are there and improve over time. Often they are improved in response to questions on the forum which indicate gaps in the docs. For example, someone wanted to know about serial ports. Hops responded and I then "wikified" his response so that it "sticks" and will be found in the future.

My plan is to continue with trac and the wiki in the short term. Longer term, I would like to replace both trac and phpBB with Cobra-based software. I would like to have a PDF export feature and also an option to edit just a section (an idea from MediaWiki).

Btw this is also a common approach with many languages. Often they have a wiki driven by a web app written in the given language. I see it all the time.

But I don't plan on pulling the trigger on this until IDE support is more mature.

Also, I'm much more interested in feedback on the content of the docs rather than whether or not we did it in bitbucket's wiki vs. trac vs. whatever.

[gourD]

Making wiki pages is not incomprehensible. I don't know why you think it is. I just made a wiki page today. It was easy.

I do not think that making wiki page is hard, just the opposite - it's too easy and that's why the whole structure is lost and you get too many pages without clear structure.

You are wrong that having hyperlinks does not improve the navigation. That's the very thing that hyperlinks are for and improve!

I believe that too many hyperlinks shows there is inherent problem with the structure.

If the content unfolds naturally, then there is less need for jumping around. I was following online development of several books where authors/contriobutors were cautious not to introduce some topic too early in order to prevent readers the need to jump from e.g 2nd chapter to the 10th one to get the idea.

I don't work much on the docs because I'm busy on the compiler.

I never wrote I expected from you to do it...

But docs are there and improve over time.

...but the point is if you recognize there is need to improve the current structure or not?

Often they are improved in response to questions on the forum which indicate gaps in the docs. For example, someone wanted to know about serial ports. Hops responded and I then "wikified" his response so that it "sticks" and will be found in the future.

This is ad hoc approach and it might be good for some topics, my humble opinion is that's not good-enough for the whole documentation

My plan is to continue with trac and the wiki in the short term. Longer term, I would like to replace both trac and phpBB with Cobra-based software. I would like to have a PDF export feature and also an option to edit just a section (an idea from MediaWiki).

Today I imported Cobra from svn to Git @bitbucket and converted (just for test case) one wiki page in order that you can try how do you feel editing wiki page at bitbucket (it's in reST markup). When you preview your changes and save, the content is available online as it is now, but it's also available in git repo which can be cloned so that those who prefer working offline can do so. You can check it here.

I believe it does not cripple online experience for those that want it, but it enhance it for offline users.

However, if you're apriori against such change (as it seems), then I won't bother any longer to try to improve it.

Btw this is also a common approach with many languages. Often they have a wiki driven by a web app written in the given language. I see it all the time.

Can you list some examples of languages depending for their docs solely on wiki docs?

Also, I'm much more interested in feedback on the content of the docs rather than whether or not we did it in bitbucket's wiki vs. trac vs. whatever.

I believe we already addressed it.

[hopscc]

Why not keeping them under VCS and using normal developer tools?

YAGNI

Havent needed any sort of VCS for this since not have multiple concurrent competing writers and not treading on each other...
After the initial seed content section edits have tended to be minor

Bitbucket would also allow you to even edit online, keep it under repo, have WYSIWYG editor (similar or better than Trac) and have preview

Already have all that (with trac wiki) , apart from explicit repo (which I have seen no need for to date) - offline creation/editing is done using my normal devt editor if that wasnt clear, trac includes preview and its already setup and up-loadable to on the cobra site.

I'd expect once written the doc would be pretty static (as content - we're not tweaking existing cobra bits much where re-doc is needed)
so any changes would be to wording or structure.
(Alternatively we are so far behind devt with the doc that we're working against a void of doc rather than outdated or incorrect doc )

(Versioned wiki docs) sounds similar to keeping one's documents in version1, version2,...,versionXYZ folders instead of using real VCS.

Its not - display looks like the same GUI rep done for diff patches so its presumably against a VCS store...
Anyway doesnt matter cos its not been needed (by me at least)

why do you stick with this incomprehensible workflow
having so many hyperlinks not improving the navigation of the docs, but just the contrary etc. instead of working to have decent tutorial, language reference, library reference etc.

I guess its not incomprehensible to me and changing to something else has no appreciable/discernable benefit I need..

Hyperlinks - Hmmpf - seems to me the existing notions of Tutorials, references, Doc are still tied to books which are limited to a mostly linear structure and notion of info display/presentation - i.e one path through the documentation/info.
Thats not necessary with hyperlinks - A linear presentation is only one possibility for the docn structure - Good for some things (tutorials say) less so for others (references, Lookup, quickDiff...).
More hyper/cross/step links ( different paths through the forest) the better.. (YOpinionMV)

None of the current doc gen process is forcing you to do the same thing... If you can make it work better doing things differently have at it...
I'll change if you can show some improvements to me that outweigh the disadvantages,
but I dont see any reason to change what is already working well enough to something that you merely assert is an improvement
for reasons I cant discern or have no personal relevance.

Now can we move off bike-shedding about what tools/workflow are the 'one true way' and follow up on what is a 'better doc structure' ???

[hopscc]

Goud,
I went to the bitbucket link you gave.
Which drops me in a login screen so first barrier is that you have to login before you can even see much less do anything,
fortunately I have a bitbucket login or I would have stopped there
when I login it says

Code: Select all


You do not have access to the wiki.

Use the links at the top to get back.


so I guess I have to get specific permission to see it in all its wonder.

username is 'hops'