Timeline for Warlords of Documentation: A Proposed Expansion of Stack Overflow
Current License: CC BY-SA 3.0
14 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Nov 20, 2015 at 19:25 | comment | added | Marsh |
You'll spend your life on that... No you won't. The users of your project will keep the documentation up to date, not you (the developers of the project).
|
|
Sep 11, 2015 at 3:00 | comment | added | The Unholy Metal Machine | @Mikl if you make a documentation for (E.G) phpbdg, I'm sure the authors will add it to the link "documentation" of the web page you pointed. Of course, I understand that if there is no doc at all, it would be better to add some somewhere. But honestly, I don't think that the case for many common APIs to don't have any documentation. So, I'm agree with you in the case there is no doc at all, but the question/proposition here is quiet more general... | |
Sep 9, 2015 at 22:44 | comment | added | Mikl | There are some languages or tools which has no documentation (online documentation) at all (phpdbg for example). If it would be a place to make docs with large experienced devs community, it'll be great place. | |
Sep 7, 2015 at 5:40 | history | edited | Qix - MONICA WAS MISTREATED | CC BY-SA 3.0 |
edited body
|
Sep 2, 2015 at 21:48 | history | edited | The Unholy Metal Machine | CC BY-SA 3.0 |
added 735 characters in body
|
Sep 2, 2015 at 7:20 | comment | added | Zev Spitz | This is actually one of the things MSDN gets right in the documentation of the Office API, VBA and some other APIs (generally the Automation APIs). Documentation is often split between How do I, Concepts and Reference -- Word, VBA, WIA. (It is admittedly almost impossible to find unless you know it's there; that is something this proposal also aims to solve.) | |
Sep 2, 2015 at 7:00 | comment | added | Zev Spitz |
What if I just want to load a 3D model, without a burning desire to use specifically function xyz in module abc ? I would also want to know all the other details as well (if not in this example then at least an easily findable linked example). Official documentation examples are often unhelpful in this respect, because it is easiest for the developers to arrange the documentation by module and function, and the example is usually tied to the specific function.
|
|
Sep 1, 2015 at 18:19 | comment | added | The Unholy Metal Machine | @ZevSpitz sorry but i'm not agree. If you want to show how to load a 3D model by using some function, you have to show the model in a window, with light and stuff... | |
Aug 31, 2015 at 22:02 | comment | added | Zev Spitz | Let's take a basic example. This proposal is less about basic single-method examples, and more about how collections of API parts can be used together, precisely like your example. | |
Aug 31, 2015 at 22:00 | comment | added | Zev Spitz | Making a good example isn't so easy. Of course it's not easy; if it was easy it would be in the official API documentation / all over the Internet already! But the users of the software can often provide more useful examples then the developer, simply because the developer 1) has a narrower focus on the precise API syntax that he/she worked on, and 2) is affected by the knowledge the internal workings. | |
Aug 31, 2015 at 17:55 | history | edited | Peter Mortensen | CC BY-SA 3.0 |
Some copy editing (but more could probably be done).
|
Aug 31, 2015 at 16:51 | history | edited | Bhargav Rao | CC BY-SA 3.0 |
added 1 character in body
|
Aug 31, 2015 at 16:39 | comment | added | NoDataDumpNoContribution | Examples could come with the API version attached they are valid for and it would always be easier to adapt them for a new version than to start from scratch. But I agree that good examples can sometimes become really large. And I also agree that the goal should be to complete the official documentation, not to build an alternative documentation. A permissive license might allow this kind of feedback. | |
Aug 31, 2015 at 16:36 | history | answered | The Unholy Metal Machine | CC BY-SA 3.0 |