Creating User Documentation for Your Product - Page 1
Forum section: electronics / general

author: metrologist
author_rank: Super Contributor
timestamp: August 03, 2016, 07:25:08 pm
content: I'm curious how this is done on a larger scale than a one-off type of deal where the engineers/developers may write content, or hire a contract technical writer, and use common tools like Word.Is anyone here familiar with modern process that allow dynamic content publication that can be tied with software (UI) development and release? What tools are available and what is the general workflow? Are these connected with development (IDEs?) or other project management tools?How or are these tools tied with marketing content?If you work for a company and are willing to share how it's done, that'd be great and I'd really appreciate it!

author: Dielectric
author_rank: Regular Contributor
timestamp: August 04, 2016, 08:27:50 pm
content: I use Doxygen for any firmware project that needs real documentation. You put tags within the source code and let the generator crawl through the tree creating a set of API docs. It's basically a way to pull the comments out into a navigable format (html). IDEs will usually have some function to create Doxygen-compatible function headers, etc., which is a great help.For user-facing stuff, I do see Word and a flowchart editor fairly commonly. I suppose the question is, who is the documentation for? Engineering, developers, end-users? How about future-you?

author: nctnico
author_rank: Super Contributor
timestamp: August 04, 2016, 08:45:49 pm
content: Doxygen is utter crap. A good programming IDE will provide the same information realtime. The problem with Doxygen created 'documentation' is that it doesn't tell anything about how a piece of software is structured andWHYa source file or function is there.For my project documentation I use Word and Visio. Usually the documentation is ahead of development.

author: SimonR
author_rank: Regular Contributor
timestamp: August 04, 2016, 09:06:44 pm
content: Quote from: nctnico on August 04, 2016, 08:45:49 pmSuch as? Name one

author: nctnico
author_rank: Super Contributor
timestamp: August 04, 2016, 09:13:55 pm
content: Quote from: SimonR on August 04, 2016, 09:06:44 pmEclipse (ofcourse). For example: When using for C/C++ I can hover the mouse over a function and it will show the function definition. Same for structs/classes. Ctrl-click on the function takes me to the function. Excellent for spaghetti code like the Linux kernel which would otherwise be a nightmare to navigate.

author: T3sl4co1l
author_rank: Super Contributor
timestamp: August 04, 2016, 09:19:22 pm
content: *Cough*To use Eclipse's structure views, you have to install Eclipse and possess the source code.Not every developer might be using... any of these.An end-user might want function names for an API. Though that would only need the public functions, and their descriptions, not the structure. Doxygen (and most codedoc tools) do visibility options, so this is fine.Doxygen probably has more output types, which is nice for perverts like me who use LaTeX.Tim

author: nctnico
author_rank: Super Contributor
timestamp: August 04, 2016, 09:48:23 pm
content: In my experience API documentation made with Doxygen isn't documentation. It is just a useless summary of functions! Often you have to go into the actual sourcecode to figure out what a function does and what it's purpose is (how does it fit into the big picture?). The problem is that many programmers don't understand how they should document an API (or software in general) so someone else can use it / maintain it. Doxygen is (often) used to produce a neat looking document so management is happy but this doesn't solve the underlying problem. If a programmer really cares about writing a proper document he/she isn't going to use Doxygen in the first place because it is not a text editing tool and takes effort to steer (for example: it is much easier to copy & paste a diagram or any picture into a Word document). Doxygen can be useful as a tool to create a list of functions and classes which can serve as a function/class overview in an appendix of the document but not as a primary source of information.

author: metrologist
author_rank: Super Contributor
timestamp: August 04, 2016, 10:01:39 pm
content: I was thinking of products such as Fluke meters, actually all the common test gear that is typically discussed here, and whatever software apps - all end user facing documentation. This usually includes lots of illustrations. I'm wondering how all that content is created, collected, and ultimately published so that in the end, the documentation matches the delivered product. Quite often, some features don't work as initially planned, may be suppressed, moved around, or modified in some way - and at the tail end of development.For example, my Rigol scope has an OK user manual, programming manual, software apps with documentation, etc. Rigol builds a lot of equipment, Keysight even more, so I wonder how they are able to keep up their user documentation with development. They must be leveraging some tools that aid in the development, management, and publication of this, but it is not apparent to me what is available.

author: SimonR
author_rank: Regular Contributor
timestamp: August 04, 2016, 11:25:32 pm
content: Quote from: nctnico on August 04, 2016, 09:13:55 pmSo Eclipse knows what every function does and what its parameters are for. And it also knows WHY a source file is there as well does it?Yes most IDEs will allow you to browse the code by clicking of a function a being taken to its definition, but the question was about documentation and that is not documentation. No IDE will know what anything is for unless you actually write some comments.Quote from: nctnico on August 04, 2016, 09:48:23 pmWell if you don’t write comments, that’s what you get. An IDE won’t solve that and nor will any other tool. No IDE currently available will “go into the actual sourcecode to figure out what a function does and what it's purpose is”, how on earth would it know?Quote from: nctnico on August 04, 2016, 09:48:23 pmUnfortunately you are spot on, I have encountered this as well. But it’s no excuse and it doesn’t mean Doxygen is crap.Quote from: nctnico on August 04, 2016, 09:48:23 pmYou are replying to this as if its Doxygens job to make up for poor comments which it is not.Just because you don’t use a tool properly it doesn’t automatically mean its crap. Microsoft visual studio works exactly the same way as Doxygen, except it uses XML instead but you still have to write the comments it not hard you just have to do this:-Code:/*** \brief A function that doesn’t do anything* \param Dummy A parameter that is not used* \arg The values of Dummy can be anything you like* \return Doesn’t return anything*/void dummyFunc(int Dummy){}In my last two jobs that was the minimum level of comments that the coding standard allowed. If I didn’t put at least that much in my code then I would be hauled across hot coals at the next code review. If you are going to comment then you might as well take the extra step and put in \param (or @parm if you prefer) then Doxygen can actually do its job. In fact if you put a couple of simple lines in header files then you get really useful information in the Modules output as well as the files sections.I now insist that my engineers write the minimum comment first and the write the function, because I know that nobody EVER goes back and writes the comment afterwards.Quote from: nctnico on August 04, 2016, 09:48:23 pmNow this is where it becomes a grey area. Doxygen is extremely good at documenting what something does, providing you actually use comments. But as you rightly point out it gets cumbersome to use from this point onwards. The sections, subsections etc are a pain to use, and don’t even think about tables unless you are an HTML guru. So if you have to explain in detail how to actually use your API then the best thing to use is a proper word processor.I’m not sure what documentation management tools are generally available. I have used one but it was unbelievably expensive.

author: SimonR
author_rank: Regular Contributor
timestamp: August 04, 2016, 11:32:05 pm
content: Just to put my money where my mouth is an example of Doxygen working properly.Note you can click on the diagram and it jumps to the related information.To get the diagrams you have to install Grafviz and change 1 single line in the doxgen config file.All of it is generated automatically. The third picture is what you get if you click on SRC in the second picture.

author: SimonR
author_rank: Regular Contributor
timestamp: August 04, 2016, 11:47:55 pm
content: And if you put a couple of lines in a module header file you get this.

author: nctnico
author_rank: Super Contributor
timestamp: August 05, 2016, 12:12:16 am
content: Your examples make my point exactly: they tell me nothing about WHY these files are there. Also comments usually provide a quick explaination of the parameters but not how a function fits in the big picture. Eclipse can do the same as the Doxygen examples you've shown. It can show an include hierarchy and when hovering over a function it shows the first few lines (where the comments on the parameters usually are) as a quick reference. Just like Doxygen Eclipse can't tell why a function is there. That should be in the design document.Let me put it differently and let's take an API as an example. With many libraries I have used the initialisation takes several calls and then some other calls to deal with data. Worse, depending on the use of the library the initialisation may need to be different and the way data is fed into the library may also differ. Things like that are hard to capture with Doxygen; you'll have to write a document which ties everything together. In short: Doxygen is a tool to generate an index of a book but you still have to write the story yourself.

author: Cerebus
author_rank: Super Contributor
timestamp: August 05, 2016, 12:43:46 am
content: Quote from: nctnico on August 05, 2016, 12:12:16 amYou've obviously never used Doxygen in ernest. There are plenty of hooks in Doyxgen for writing proper documentation, a prime example of which is the Doxygen manual itself which is generated using Doxygen. You can't go blaming Doxygen for people not writing proper documentation just as you can't blame Word or Pagemaker. Some human has to have the will to sit down and write proper documentation whatever tool is used to get the words on the page. The advantage Doxygen has is that, used properly, the code and documentation are all in one place and the finished products (machine executable code and human readable pdfs or HTML) are amenable to generation with makefiles (or similar) and the file formats neatly fit in with version control systems (which is a nightmare with binary formats like Word).

author: Cerebus
author_rank: Super Contributor
timestamp: August 05, 2016, 01:07:38 am
content: Quote from: metrologist on August 04, 2016, 10:01:39 pmMy experience isn't particularly recent (mid-late 90's) but I suspect little has changed. There's no magic sauce. For everyday manuals like Keysight's the work is nearly always done by professional technical writers (in-house or freelance) and the tools they use are the same as writers of the printed word the world over. That is, the usual DTP tools packages like PageMaker, FrameMaker, Adobe Illustrator, InDesign, Quark Express etc. etc. I can tell you from first hand experience that 3Com used to use Word, PageMaker and Corel Draw; and if you had to use a 3Com Token Ring product in the mid nineties you were probably reading a manual written by me. The only tools that these professional manual writers use that other writers of the printed word don't are the whips, thumbscrews and chains necessary to get the engineers and programmers to co-operate when required and the rubber gloves and disinfectant necessary when dealing with Marketing.The one exception to using standard off the shelf DTP software is people like Boeing who have a massive documentation load and regulatory obligations to go with it. They tend to use highly specialised packages based around an SGML core that, if you can't afford a team of lawyers to read the software licence, you can't afford the software package.

author: SimonR
author_rank: Regular Contributor
timestamp: August 05, 2016, 01:36:18 am
content: Quote from: nctnico on August 05, 2016, 12:12:16 amName a tool that does

author: SimonR
author_rank: Regular Contributor
timestamp: August 05, 2016, 01:41:47 am
content: Quote from: nctnico on August 05, 2016, 12:12:16 amThat doesn't justify calling it crap.Of course you write the story yourself.Yes of course we generate the usual documentation, product specification, enginerring design and we use what ever tool is appropriate etc. Doxygen happens to be the best to to document the actual code created but when you are developing you want quick access to the info on the bit you are working on. So the module level pages contain the text from the spec or the design document. The device drivers have text from the manufactures datasheets, and they all have references to specification pages or URLs to the relavent datasheet if more than just text is required.If you click on any of the title inthe module section you will get a full explanation of what the module is for and how it works. I'm not going to post the details as they are confidential, but attached is one of the related pages on how to set up tools in the IAR IDE I used for this particular project. I shows the level of detail you can get

author: wblock
author_rank: Regular Contributor
timestamp: August 05, 2016, 01:53:23 am
content: Somebody should mention tools that don't have the binary problems of Word:DocBook (the big one)AsciiDoc and AsciiDoctorSphinx (reStructuredText)All of these have the advantage that the source text is plain ASCII. It can be kept in a version control system and you can get diffs and generally treat it like any other source.AsciiDoc and rST are pretty similar. They are simpler than DocBook but lack some of the power. Many projects don't need much power.All of these can produce various output formats, including text, HTML, PDF, and EPUB.

author: SimonR
author_rank: Regular Contributor
timestamp: August 05, 2016, 02:17:53 am
content: Interesting, Do you have links to any of those

author: SimonR
author_rank: Regular Contributor
timestamp: August 05, 2016, 02:20:57 am
content: Don't worry I found themhttp://www.docbook.org/docs/http://www.methods.co.nz/asciidoc/#_introductionhttp://www.sphinx-doc.org/en/stable/

author: nctnico
author_rank: Super Contributor
timestamp: August 05, 2016, 05:29:03 pm
content: Quote from: SimonR on August 05, 2016, 01:36:18 amThere is no such tool. And I never claimed such a tool existed. My claim is that such a tool can never be made based on sourcecode because sourcecode is a result of the thought process. It is the thought process itself which needs to be captured into a document in order to make meaningfull documentation (on any level) because it will explain why something works the way it has been made so the user understands how he can apply a piece of software (or tool) in order to achieve his/her goal.

author: Jeroen3
author_rank: Super Contributor
timestamp: August 05, 2016, 07:40:16 pm
content: All tools are crap if you don't know how to use them!You CAN make proper documentation for something in doxygen if you know how. Even for non-software. (I currently have no examples, but I have seen some)http://www.kvaser.com/canlib-webhelp/index.htmlEven if you don't. The style of commenting like doxygen does create some harmonised structure to the file. Which is a good thing.In other relevent news to the above:https://blog.stackoverflow.com/2016/07/introducing-stack-overflow-documentation-beta/?cb=1But that wasn't the question:Quote from: metrologist on August 04, 2016, 10:01:39 pmAt work there is Word with Visio support images. It's bottomless time hole. No version control. Layout inherited from Wordperfect. Nobody knows how to properly layout stuff. Nobody even cares as long as the PDF looks fine. Inserting visio to word without creating a unprintable document. Transparencies. Different versions than your co-worker. Not very developer friendly at all.But an important lesson has been learned recently:People don't read the text.That's why you must insert diagrams, pictures and schematics. And add shorts notes. Otherwise people will call for basic stuff you can find in themanual.Don't hide wiring diagrams in the pdf. Add it as a centerfold to the manual, for example.Since above is such disaster. I started looking into rendered document creation. The main benefit is that it iscompatible with version control.Such asLaTeX.However, I've yet to start with that. There are so many "ide's" for it. Any recommendations?Other ways would be to make an webpage, such ashttps://docs.particle.io/guide/getting-started/intro/electron/Depends on your target audience. I would prefer an .pdf since that is always offline available. But that would be pointless with the above example.

author: T3sl4co1l
author_rank: Super Contributor
timestamp: August 05, 2016, 08:16:42 pm
content: Regarding LaTeX, any versioning editor will do; I don't know offhand of any that's purpose-made, or which includes repository functionality. Does Notepad++ do that?...For compiles, at least: there's a package for that, vrsion. Saves a counter in an aux file, increments on every run. Plus commands to set and change version numbers IIRC.Tim

author: Buriedcode
author_rank: Super Contributor
timestamp: November 03, 2016, 12:11:50 am
content: Sorry to rekindle this thread, but I am increasingly facing situations where I do everything for a project, including documentation. I've noticed this thread take a turn towards documenting software/firmware and API's, but there is also the matter of 'user guides', explanation of functionality and of course illustrations.Now, everyone wants to have very nice looking docs but the last time I did anything serious, 'clipart' was still overly used (for the record, I refused to use clipart, non-schematic diagrams were either taken from AutoCAD, drawn up in paint.. or hand drawn). Often they we either for other engineers in which case is was diagrams and well indexed explanations, or end-user 1-2 page 'guides'.Aside from screenshots, with the obligatory highlighting specifics areas, schematics captured from CAD how do people draw up illustrations?And as for the text, I always run into LaTeX, but have yet to step out of using basic MS word and printing out as a PDF. There seems to be a wide range of styles and quality with things like consumer manuals, but it would be nice to get a template, customised without having to pay out for software or spend an age formatting. Examples are always welcome.I recently got the manual for a fitbit for a friend. This is of course aimed at the consumer rather than engineer, but seems quite sleek in terms of style.https://staticcs.fitbit.com/content/assets/help/manuals/manual_flex_en_US.pdf