This is the
talk page for discussing improvements to the
Software documentation article. This is not a forum for general discussion of the article's subject. |
Article policies
|
Find sources: Google ( books · news · scholar · free images · WP refs) · FENS · JSTOR · TWL |
![]() | This ![]() It is of interest to the following WikiProjects: | ||||||||||||||||
|
User documentation for software, especially complex software, is a thing of the past. Big, money-making software publishers believe GUIs have eliminated the need for good user documentation, because the point-and-click paradigm is so simple, so self-explanatory, a child could use it. Of course, this is a rationalization that, in a way, justifies not spending a dime on explaining how their highly profitable products may be used, since people can "discover" what they need to know by fooling around. Alternatively, context-sensitive help may be perceived as a substitute for use case by usage scenario coverage of every feature. The people in the best position to publish effective user documentation (because they understand the motivations and the details) don't do it. So technical publishers hire technical writers who take a stab at the task and fail as often as they succeed to fill the gap. Such a shame!-- 72.75.76.186 02:49, 20 December 2006 (UTC)
Should clarify what IS means in "outline what the IS situation is". -- AlastairIrvine 03:24, 1 May 2007 (UTC)
This is silly. Software documentation is a broad concept that covers many many things. A Linux HOWTO is a specific instance of software documentation. Merging HOWTO into Software Documentation would be like merging Apple into Fruit. 66.80.155.65 ( talk) 18:37, 15 May 2008 (UTC)
Against. As stated above software documentation is a broad topic and HOWTO is discretely different Paullb ( talk) 08:09, 23 October 2008 (UTC)
Against. The topics, as in their generality, are different. Software documentation is a broad topic entirely focused on software, of which software HOWTO is a particular type. HOWTOs are manuals / instruction procedures and in their generality can be referred to anything, software included. —Preceding unsigned comment added by 210.254.37.34 ( talk) 05:21, 31 July 2009 (UTC)
I can't find anything leading to the following statement in the reference provided. How about a page number or a link to the actual page?
"Tutorial: A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks [1]." ^ 1. Woelz, Carlos. "The KDE Documentation Primer". http://i18n.kde.org/docs/doc-primer/index.html. Retrieved 15 June 2009. —Preceding unsigned comment added by 86.27.207.197 ( talk) 17:13, 22 April 2010 (UTC)
Why is that section even in this article? Marketing software and documentation for software are two different things. I would suggest merging the section into another article, but given the fact that it's unsourced, I suggest that it simply be deleted; it has no relation to the topic. MezzoMezzo ( talk) 09:42, 26 February 2013 (UTC)
Hello fellow Wikipedians,
I have just added archive links to one external link on
Software documentation. Please take a moment to review
my edit. If necessary, add {{
cbignore}}
after the link to keep me from modifying it. Alternatively, you can add {{
nobots|deny=InternetArchiveBot}}
to keep me off the page altogether. I made the following changes:
When you have finished reviewing my changes, please set the checked parameter below to true to let others know.
This message was posted before February 2018.
After February 2018, "External links modified" talk page sections are no longer generated or monitored by InternetArchiveBot. No special action is required regarding these talk page notices, other than
regular verification using the archive tool instructions below. Editors
have permission to delete these "External links modified" talk page sections if they want to de-clutter talk pages, but see the
RfC before doing mass systematic removals. This message is updated dynamically through the template {{
source check}}
(last update: 5 June 2024).
Cheers. — cyberbot II Talk to my owner:Online 15:06, 27 August 2015 (UTC)
I think the current article is great. It explains all the theory about software documentation. The article explain how things should be. Nice :-)
If I look at the READMEs at github, I see a big mistake which gets done over and over again. Developers start with "installing", then the next topic is "configuration".
What is missing? The **introduction**. Most READMEs at github don't provide an overview what the software is all about. They don't explain
Most developers (inclusive me) are bad in writings docs.
I would like to have section about this topic:
- Docs get outdated soon. That's why a lot of developers don't use comments any more: Code should be readable on its own. - Details get documented, but high level view gets neglected.
Ask yourself: What comes to your mind if you thing at "software documentation".
In my head its "absent" "no docs".
I am not a native speaker, and that's why I don't have the courage to create a new section.
I am open for discussions, you can reach me at guettliml@thomas-guettler.de — Preceding unsigned comment added by Guettli ( talk • contribs) 09:12, 2 December 2016 (UTC)
There is a move discussion in progress on Template talk:IEEE software documents which affects this page. Please participate on that page and not in this talk page section. Thank you. — RMCD bot 22:02, 15 June 2020 (UTC)
Is the "Documentation and agile development controversy" section needed? 104.228.101.152 ( talk) 20:16, 18 March 2021 (UTC)
e7a41591abe909f20eb303f1c156c02e 120.89.104.81 ( talk) 05:53, 21 November 2023 (UTC)
This is the
talk page for discussing improvements to the
Software documentation article. This is not a forum for general discussion of the article's subject. |
Article policies
|
Find sources: Google ( books · news · scholar · free images · WP refs) · FENS · JSTOR · TWL |
![]() | This ![]() It is of interest to the following WikiProjects: | ||||||||||||||||
|
User documentation for software, especially complex software, is a thing of the past. Big, money-making software publishers believe GUIs have eliminated the need for good user documentation, because the point-and-click paradigm is so simple, so self-explanatory, a child could use it. Of course, this is a rationalization that, in a way, justifies not spending a dime on explaining how their highly profitable products may be used, since people can "discover" what they need to know by fooling around. Alternatively, context-sensitive help may be perceived as a substitute for use case by usage scenario coverage of every feature. The people in the best position to publish effective user documentation (because they understand the motivations and the details) don't do it. So technical publishers hire technical writers who take a stab at the task and fail as often as they succeed to fill the gap. Such a shame!-- 72.75.76.186 02:49, 20 December 2006 (UTC)
Should clarify what IS means in "outline what the IS situation is". -- AlastairIrvine 03:24, 1 May 2007 (UTC)
This is silly. Software documentation is a broad concept that covers many many things. A Linux HOWTO is a specific instance of software documentation. Merging HOWTO into Software Documentation would be like merging Apple into Fruit. 66.80.155.65 ( talk) 18:37, 15 May 2008 (UTC)
Against. As stated above software documentation is a broad topic and HOWTO is discretely different Paullb ( talk) 08:09, 23 October 2008 (UTC)
Against. The topics, as in their generality, are different. Software documentation is a broad topic entirely focused on software, of which software HOWTO is a particular type. HOWTOs are manuals / instruction procedures and in their generality can be referred to anything, software included. —Preceding unsigned comment added by 210.254.37.34 ( talk) 05:21, 31 July 2009 (UTC)
I can't find anything leading to the following statement in the reference provided. How about a page number or a link to the actual page?
"Tutorial: A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks [1]." ^ 1. Woelz, Carlos. "The KDE Documentation Primer". http://i18n.kde.org/docs/doc-primer/index.html. Retrieved 15 June 2009. —Preceding unsigned comment added by 86.27.207.197 ( talk) 17:13, 22 April 2010 (UTC)
Why is that section even in this article? Marketing software and documentation for software are two different things. I would suggest merging the section into another article, but given the fact that it's unsourced, I suggest that it simply be deleted; it has no relation to the topic. MezzoMezzo ( talk) 09:42, 26 February 2013 (UTC)
Hello fellow Wikipedians,
I have just added archive links to one external link on
Software documentation. Please take a moment to review
my edit. If necessary, add {{
cbignore}}
after the link to keep me from modifying it. Alternatively, you can add {{
nobots|deny=InternetArchiveBot}}
to keep me off the page altogether. I made the following changes:
When you have finished reviewing my changes, please set the checked parameter below to true to let others know.
This message was posted before February 2018.
After February 2018, "External links modified" talk page sections are no longer generated or monitored by InternetArchiveBot. No special action is required regarding these talk page notices, other than
regular verification using the archive tool instructions below. Editors
have permission to delete these "External links modified" talk page sections if they want to de-clutter talk pages, but see the
RfC before doing mass systematic removals. This message is updated dynamically through the template {{
source check}}
(last update: 5 June 2024).
Cheers. — cyberbot II Talk to my owner:Online 15:06, 27 August 2015 (UTC)
I think the current article is great. It explains all the theory about software documentation. The article explain how things should be. Nice :-)
If I look at the READMEs at github, I see a big mistake which gets done over and over again. Developers start with "installing", then the next topic is "configuration".
What is missing? The **introduction**. Most READMEs at github don't provide an overview what the software is all about. They don't explain
Most developers (inclusive me) are bad in writings docs.
I would like to have section about this topic:
- Docs get outdated soon. That's why a lot of developers don't use comments any more: Code should be readable on its own. - Details get documented, but high level view gets neglected.
Ask yourself: What comes to your mind if you thing at "software documentation".
In my head its "absent" "no docs".
I am not a native speaker, and that's why I don't have the courage to create a new section.
I am open for discussions, you can reach me at guettliml@thomas-guettler.de — Preceding unsigned comment added by Guettli ( talk • contribs) 09:12, 2 December 2016 (UTC)
There is a move discussion in progress on Template talk:IEEE software documents which affects this page. Please participate on that page and not in this talk page section. Thank you. — RMCD bot 22:02, 15 June 2020 (UTC)
Is the "Documentation and agile development controversy" section needed? 104.228.101.152 ( talk) 20:16, 18 March 2021 (UTC)
e7a41591abe909f20eb303f1c156c02e 120.89.104.81 ( talk) 05:53, 21 November 2023 (UTC)