Comments (6)
yes!
from standard-readme.
Thanks! This is great.
from standard-readme.
Thanks! Worked some of these in. I think they are perl specific, sometimes, and I want to keep this as general as possible.
from standard-readme.
Here are a few tidbits that are pretty general but extremely spot on:
from perlmodstyle
:
The level of detail in Perl module documentation generally goes from
less detailed to more detailed. Your SYNOPSIS section should
contain a minimal example of use (perhaps as little as one line of
code; skip the unusual use cases or anything not needed by most
users); the DESCRIPTION should describe your module in broad terms,
generally in just a few paragraphs; more detail of the module's
routines or methods, lengthy code examples, or other in-depth
material should be given in subsequent sections.Ideally, someone who's slightly familiar with your module should be
able to refresh their memory without hitting "page down". As your
reader continues through the document, they should receive a
progressively greater amount of knowledge.
from http://mathforum.org/ken/perl_modules.html#document:
Your documentation is complete when someone can use your module without ever
having to look at its code. This is very important. This makes it possible for
you to separate your module's documented interface from its internal
implementation (guts). This is good because it means that you are free to
change the module's internals as long as the interface remains the same.Remember: the documentation, not the code, defines what a module does.
from standard-readme.
I should merge these thoughts in with a reasoning for each section in the spec. Reopening to remind myself to.
from standard-readme.
from standard-readme.
Related Issues (20)
- Improvement in License section HOT 1
- Question on Usage section HOT 1
- Question: clarifying on rules for install, usage, and contributing HOT 3
- Installation fails because of missing dependency to opencollective-postinstall HOT 1
- README.cn.md doesn't follow naming convention HOT 8
- Introduce REUSE compliance/compatibility HOT 1
- 您好,能写一个新手能看懂的教程吗?
- cat: spec.md: No such file or directory HOT 1
- README, Markdown and other formats HOT 1
- It's a good markdown file HOT 1
- Create a logo for Open Collective
- The "Install" section may not seem right for deployable websites HOT 2
- Does this project comply with standard-readme HOT 1
- Table of Contents Built in to GitHub HOT 2
- Demo
- Some links in the maximal example are broken HOT 4
- Add support for CHANGELOG.md? HOT 2
- Add a Credits/Thanks/Acknowledgements section HOT 6
- Examples use "contributing" which results in an error HOT 3
- Chinese translation HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from standard-readme.