Hi All, my 1st new post!
Currently I have been tasked to establish content structure and design the organisation’s product documentation online. I am currently using stripe connect as one of my primary baseline.
Just wanted to hear from the wider community if you have a preference or just seen a great & amazing document online lately, please let me know or message me.
Thanks.
Personally my level of expectation with documentation has sunk to “Is it written in English that actually includes an article here or there, and is at least 50% accurate to the technical task at hand?” and when the answer to that is No, to make 300 comments on a 20 page document and send it back.
Just keep it to the point, keep it in the right language, use a spell checker and if you’re feeling frisky, something like Grammarly to keep your sentences intact, and the world will be happy with it.
I may be slightly jaded in this particular field.
Signed
The QA Engineer that has to redo the product documentation for the fourth time.
The most important feature of documentation is to write it for anyone that does not already understand it can understand it. It seems really difficult for many people to think from the point of view of someone that does not already understand it.
I suggest writing the documentation in any format then design a format. You are more likely to develop something good that way than if you design a format then make the documentation fit that.
Also, if you want abundant compliments and appreciation and amazement then start with the concepts. I have never read a technical book that has done that, certainly not effectively. It is easy to dump a bunch of details, but if you want to explain a new system to others then do this: transfer the knowledge you have of the concepts so they know how to arrange and later find the details in their head.
I am impressed with the online PHP documentation especially since it has over 3,000 functions!
Adding a couple of key words to a "“PHP manual” search is usually sufficient to find the exact page with:
I cannot provide examples at the moment but I consider the PHP manual to be inferior. As for user posted comments, many of them should be merged into the main documentation and the user contribution facility does not make it easy for everyone to do that.
IBM and NCR Corporation have existed for more than a century, although the name International Business Machines is slightly under a century old. IBM has developed thousands (List of IBM products - Wikipedia is a partial list) of hardware and software products, including many computer languages and operating systems. The Microsoft Developer Network has many more than 3,000 functions. The MSDN is an excellent example of the wrong way to do things; their transfer of concepts is lousy.
Microsoft has however converted over to GitHub for much of the documentation. Perhaps that concept is useful here. GitHub requires knowledge of Git so it is not a good solution for non-technical people but if relevant, a system allowing people to submit suggested improvements and a system to allow the improvements to be reviewed prior to implementation might be very useful. Perhaps the question should ask about that or a separate question be created for that.
I’m not sure what the IBM/NCR namedrops were meant to prove? Other than to say “just because you document a lot of things doesnt mean its done right”.
That said, the PHP manual is, IMO, a decent example of a lookup based documentation. It’s not really intended to teach php, but as a reference (which, for what it’s worth, is what those pages are listed as - a Function Reference), it’s fine documentation.
Though that does perhaps point to a fundamental of documentation - have a defined audience and scope for the document. If it’s meant as a technical reference, write a technical reference. If it’s a Startup guide, write a startup guide.
Hey All,
Thanks for all the great responses, and really enjoy the many different opinions and perspectives. This will really help me set some views on how to approach documentation.
Thanks again.
I did not attempt to prove anything. You are misinterpreting what I meant. I might misunderstand what you mean by namedrop but if it is meant to be something like spam then I notice that people react that way when they do not like something. And I am not sure what you mean by just because you document a lot of things doesnt mean its done right except you seem to assume they do not do it right. Actually IBM has had thousands of employees, many of which whose job it was to improve documentation. They have worked with thousands of businesses, including providing help developing documentation. I am confident in saying that IBM has invested man-years in the subject of documentation.
The main point I was making is that the world is much larger than what many of us see. PHP is just a small part of what is out there. My mention of IBM and NCR might seem strange to you but they certainly have produced abundant documentation. There is much more to the world of documentation than PHP.
Hi. I work for NCR. I don’t assume. I know. 
But feel free to make your own assumptions.
The critical assumption I am making is that the world of documentation is much larger than what most of us encounter.
This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.