Lobster wrote:I have done a lot of trials for tmxxine on documentation and my conclusion is this:
Content is more important than format
Totally agree. I don't care about the format at all! I mentioned pdf just because someone else in the forum said they want it (they may have some points thou, as html print differently on different computers with different browsers; with pdf it looks the same whereever you print it)
Lobster wrote:One of the great things about Puppy is the wizards - which also EXPLAIN what is being done and why.
Sure! Puppy wizards are great! They teach me a lot
Lobster wrote:The simpler and more obvious and functional something is the less documentation
I don't think Puppy should have too much docs either. I like simple things too (so I seldom write very long documentation
)
So don't take me wrong, I'm NOT focusing on the format. What I mean really is:
puppian wrote:...pages are well-organized and all pages look the same/similar in style, though they are written by different people...
IMO an ideal documentaion software should be something like this:
1. simple and easy to use
2. have things like templates; e.g. the user only have to imput the content in an input box (much like posting in this forum), but there would be more than one input box. so the content of each box becomes a section of the output page (similar to 'section-editing in Media wiki?); this way only few formatting rules are needed (only BBCode perhaps); and editing is done mostly in plain text
3. user can select which catergory a page go to after creating it with just one click
4. table of content / sitemap and index are generated automatically (again with just one click
)
5. output files are easy to navigate (with menu/sidebar/anchor, etc)
6. easy submition/integration of new docs by different writters (e.g. people just click a "submit" button to submit a new page and the table of content...etc, are updated automatically)
7. can convert all docs to any format (html, txt, doc, pdf...) at one time with just one click (thus people can download the whole thing in one file if they wish); version history/management
8. can work offline is a plus
I don't know if such kind of software exist. I'm not sure docBook is anything close to it and so I asked...still, no one is telling me how docBook works or what's "SGML document type definition"... no one knows?
PS. Actually I'm inspired by
this page you sent me to, which is clean and organized. I think they mentioned docBook somewhere (but I can't find it now) and that led me to do a search of that software.