forked from CRIStAL-PADR/reproducible-research-SE-notes
-
Notifications
You must be signed in to change notification settings - Fork 1
/
project_documentation.pillar
128 lines (86 loc) · 7.24 KB
/
project_documentation.pillar
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
!! Project Documentation
Defining and starting a new software project is a routine task for a software engineer.
We carve new ideas all the time into software programs.
And we organize these software programs following well-defined structures.
Of course, we know the technology and how projects should be structured for them.
And if we do not know the technology, we know the exact keywords to look for in a web search.
This is not the case for those people not experienced with software engineering practices.
The lack of terminology, the lack of contacts, the lack of experience are a high entry barrier for newcomers.
You are starting a software project.
You are maybe building a product for your business or a cool startup.
Or maybe you are designing a library to share to the scientific community.
Or you are perhaps doing it just for the fun.
Documentation is key for a software project, since it is probably one of the strongest reasons of adoption of a technology.
Likewise, if your project is not documented, people will probably run scared.
No documentation could be read in many ways: difficult entry barrier, no support, no updates, too unprofessional...
This chapter will describe several tips about how to document your project.
!!! Describe your project
The first main reason why a user may run away from your project is because he does not really understand what is it, or why should he use it.
!!!! Choose a Project Name
The first thing that your project needs is a name.
Without a name, you cannot create a first directory in your disk to store your source files.
Without a name, you cannot tell people how to search for your project.
A name give your project an identity, a way to refer to it and to differentiate it from other projects.
!!!!! What is a good name?
Naming is hard.
Donald Knuth, one of the biggest minds ever in computer science said that choosing a good name is one of the two most difficult tasks in computer programming (for the curious reader, the other one is cache invalidation).
Indeed, choosing a good name requires understanding the nature of what we are naming.
Good names do not always take the same form but they have something in common: in one way or another they are easy to remember.
Some names, like Google, are easy to remember because they are catchy.
Some other names, like Python or apache, are good because they relate to an existing idea or concept.
Some others, like Ubuntu, use catchy words in foreign languages.
However, there are actually no strict rules to get a good name.
!!!!! Some Ideas
In general, I use two main approaches to chose a name: acronyms and fantasy names.
Acronyms are useful when you want to reflect some idea in the name directly.
For example, a project whose long name is "Can be an acronym" can be transformed in the acronym CaBAnA (Can Be An Acronym).
Acronyms are good if you want to embed specific words or affiliations inside the name.
They are also handy when you miss the inspiration for a better fantasy name.
A different alternative to name your project is to use a fantasy name.
We call fantasy names those names that are not necessarily forged like the acronyms.
Instead, a fantasy name is taken or inspired from existing concepts.
Some examples of this are the Apache Spark platform, or the Oracle SQL database.
Fantasy names can have also have a metaphor.
Good metaphors relate easily to the project and, if we know it, it helps in remembering it.
Typical metaphorical names are inspired in mythology, books.
Finally, sometimes you will need to adjust your name to the technology conventions or limitations.
For example, some tools require special casing: start with uppercase or lowercase, spaces allowed or forbidden, underscores or not, etc.
!!!!! About Bad Names
As there exist good names, there exist also bad ones.
Again, there are no strong rules that say if a name is good or bad, but I like to follow some guidelines.
First, I avoid long project names.
Long names are harder to remember, to type, to web-search than short names.
Second, I avoid acronyms with too many consonants because they may turn difficult to pronounce.
And a name that we cannot pronounce, we cannot promote with the parole.
!!!! Explain What does your Project do
People will arrive to your project's main page because they are looking for similar stuff. Or maybe because somebody linked you. And sometimes even for random.
Most of the people that will arrive to your project's page will have something in common: they do not know your project.
And people now knowing your project will ask the following questions as soon as they arrive to your site: What is it? What is it useful for? Why should I use it?
Most of the people will abandon your site if they do not find any of these explanations.
The README file is the first entry point to your GitHub project, that's why it must be crystal clear: write for newbies.
Most people will be users of your code.
Their main concern is to know what your code is about, not the detail of what happens inside, they want to understand what can they use it for.
Give examples of usage, tell the user if he's the right person for your code.
Of course this does not mean that you don't have to do a technical documentation of the internals of your project. You need technical documentation, but it is not a friendly way to welcome new users.
!!! Add Installation Instructions
The second main reason why a user may run away from your project is because he does not really understand how to use it.
!!!! Platform
Explain what technology you use so they can understand if your project really fits with their technological stack.
Lots of people have lots of different needs and experience, so clearly stating what you propose creates a healthy contract.
Explain amongst others:
- What programming language/s is your system build on: is it python, ruby, java, smalltalk? Or a mixture of python and C?
- What build system do you use: pip, gems, maven, metacello?.
- Does your project run on any machine and architecture? 64bits and 32 bits? linux and mac? What about windows?
In general, try to explain any specificities about your project.
!!!! Dependencies
Describe what are exactly the dependencies of your project.
A dependency is a library or a service that is external to your project, without which your project could not work.
Even if the loading of your project is completely automated, a user may want to know what are its dependencies, because he could find that some of them create conflicts with his dependencies or come from sources he does not trust.
The simplest dependency you could imagine are those written in the same language you use. These libraries are usually easily loadable using the package manager of your language.
A separate level of dependency are dependencies written in separate languages. These usually need some more glue code to be used and downloaded, adding some bureaucracy. The most prominent example of these are native libraries written in C or C++. Sometimes such libraries can be installed using a separate package manager (such as ubuntu and debian's apt). However, some other times these libraries have to be manually compiled and installed into the user system.
!!!! Build, Compile
!!!! Verify your Installation
!!! Explain How to Use Your project
!!!! Document the API
!!!! Extension Points
!!!! Add Examples