Re: Some musings on online documentation

I wouldn't think that writing a basic HTML4 (no JS) browser in Tk would be that difficult. HTML::Parser and a dispatch table should do the trick. (Note: I have exactly 0 Tk experience.)

As for userdocs in general ... I have to disagree with you. The best people to write and edit user guides are power users. The best people to provide feedback on user guides are novice users. So, merge the two of them together, a la the MySQL manual.

Anyone can add comments to the documentation. These can be questions, clarifications, answers to prior questions ... whatever is appropriate
When a comment is added, an email is sent to the moderator(s) of that page/section/manual
The moderator(s) may remove comments and edit the documentation, as appropriate

The moderator(s) should include a developer, a tester, and several end users who have volunteered for this. They should meet at least once a month to go over anything that pops up.

Now, in terms of the docs themselves - I would have the documentation maintained in a source control repository - my favorite is Subversion. This way, whenever an app loads, it can go ahead and update to the latest version of the docs.

You can also track how the user guide has changed over time, so that the next user guide that's written can be done with "lessons learned" in mind.

My wife's blog

Comment on Re: Some musings on online documentation

Replies are listed 'Best First'.
Re^2: Some musings on online documentation by hardburn (Abbot) on Apr 18, 2005 at 13:40 UTC
I wouldn't think that writing a basic HTML4 (no JS) browser in Tk would be that difficult. HTML4 is rather complex, and contains a lot of details that aren't useful for documentation. You almost certainly won't need frames or forms, for starters. You would probably be better off with a restricted subset of XHTML. `<p>, <b>, <i>, <img>` and maybe `<table>` and `<ul>/<ol>, <li>` are probably all you need. That will be far easier to parse than full (X)HTML. "There is no shame in being self-taught, only in not trying to learn in the first place." -- Atrus, Myst: The Book of D'ni.	[reply] [d/l] [select]

Replies are listed 'Best First'.

Re^2: Some musings on online documentation
by hardburn (Abbot) on Apr 18, 2005 at 13:40 UTC

I wouldn't think that writing a basic HTML4 (no JS) browser in Tk would be that difficult.

HTML4 is rather complex, and contains a lot of details that aren't useful for documentation. You almost certainly won't need frames or forms, for starters.

You would probably be better off with a restricted subset of XHTML. <p>, <b>, <i>, <img> and maybe <table> and <ul>/<ol>, <li> are probably all you need. That will be far easier to parse than full (X)HTML.

"There is no shame in being self-taught, only in not trying to learn in the first place." -- Atrus, Myst: The Book of D'ni.

[reply]
[d/l]
[select]