Just to play devil's advocate:
One thing you may want to consider is that your current documentation might be suboptimal - no one may be reading your documentation because it isn't useful (to them).
How easy is it to find your documentation in the first place?
How easy is it to find a given topic within your documentation?
Is there a clear path for a ...
The Berne Convention on copyright specifies the Right to Quote as an exception to copyright.
Article 10 (1) It shall be permissible to make quotations from a work which has already been lawfully made available to the public, provided that their making is compatible with fair practice, and their extent does not exceed that justified by the purpose, including ...
There are a bunch of strategies that help you deal with beginner questions. Not all of them teach to RTFM, but you don't have to. Some strategies that can be very effective:
Mobilize your userbase for support. Have a proper real-time communication platform (IRC, commonly on Freenode, and/or Gitter) to ask questions, as well as a mailing list. Users can help ...
Don't merge, unless it meets your demands. All contributions are welcome, but only those that meet your standards are merged.
Whether that is test coverage, a style guide, or documentation, it shouldn't be merged until it's OK. You can choose to do it yourself when you're merging, or you can turn down the patch until it does.
As the maintainer, you are ...
Think of it this way:
how much documentation would I like to be available when I visit an open source project?
Answer: a lot
how much documentation is enough?
Answer: there is never enough documentation!
Now there are several things to consider:
Making a great first impression matters
For this you want to have a clear one liner that describes ...
"Nobody" reads the f-ing manual.
But let me detail my answer a bit. It's statistics you see...
One only reads the manual when there is absolutely, positively nobody around that even remotely has knowledge on the subject matter. Anything, everything is better than the manual, because the manual doesn't contain THE answer to your question, it also contains ...
Requiring people to contribute their changes back to the original project is a bit of a problem point for licenses.
For open-source license, such a requirement fails the "desert island test" and prevent the license from being an open-source license. The desert island test means that a group of people on a desert island with no way of contacting the outside ...
As a project leader, for years I have tried to answer every single question coming to the mailing list of my user-oriented software, and I have found that:
Many users can't read much English and don't have the skills to search/locate information efficiently
Some users won't read the documentation even under torture
Some users don't really trust the ...
Since you are using .md file, I take it that people won't be looking at the raw stuff with all the stars and what not. People will look mostly at the way that the file is "marked down". This means that you can use headers, and emphasis just like you note.
There isn't really a "standard" of doing this: Most projects create their own policies and standards to ...
Things like this happen all the time. Stack Overflow, Google Devs...
First off, we need to look at ways to license.
Stack Overflow works by licensing all content, text and code, under the Creative Commons Attribution Share Alike license.
Google Developers works by licensing all code under the Apache 2.0 license, and all other content under the Creative ...
Is there any particular reason to license docs with CC BY 4.0 rather than MIT?
The MIT license was originally designed primarily for software code (and its related documentation).
The CC licenses family was originally designed for content such as books, music, etc.
Because of this history, it happens that some projects use two different licenses: one for ...
There's really no standard; it's all up to you.
For example, do I need to include information about how the code itself works? About how to use the program? How in-depth does it need to be?
I generally write documentation primarily for users. That means including information on:
What problem this solves ("Why would I use this?")
How to install it
How to ...
I think you're missing out on a couple things: motivation, and a suitable quality standard.
It seems as if your developers aren't totally motivated. Many people (including myself) are interesting in writing the code, testing it and seeing if it works, not doing the paper work all the time for other people. The programs that I wrote in school normally ...
Apart from the earlier suggestion to make "Documentation" a very prominent link, perhaps the mechanism for asking questions should enforce the "search here first" paradigm.
Questions? Please type your question in the form of a Google query here :
<give some examples of queries>, e.g.
"Tutorials regarding Twig"
Then run the search on your site and ...
We can both write a HelloWorld application in the same language and chances are that both programs will look very similar. This does not mean that, if I were to publish mine first, that your version would be derived from mine. Both are independent works, no matter how similar they look.
Copyright law and -judges also recognize the fact that as there become ...
IMHO the existence of a book which provides detailed guidance and instruction on the use of a tool, but which costs money, does not negate the FLOSS nature of the product itself.
Though admittedly a weak analogy, gcc meets all the criteria for Free Software. But to really master C++ or C you will inevitably need to read some books on the subject, and many ...
This isn't really relevant for Open Source Stack Exchange, but as far as the installation of documentation on a Unix-style system goes, I'd simply adapt the FHS location for documentation to /usr/local: install the documentation in /usr/local/share/doc/gitless.
As apsillers says, you (as a user) don't need to keep a copy of the license along with the binary....
The theory is that if you redistribute all the deps (and least for all embedded deps) then you would be responsible to comply with their license (including attribution, etc). And this is for all the direct deps and deps of deps, all the way down.
Now for the deps you do not distribute but would be installed by a user of yours at build time, you do not need ...
It's often just a matter of manageability. A lot of developers like to keep their source control "lean and mean", which only the relevant project files there, and leave the "fluff" pieces, such as guides, documentation and analysis documents to be hosted elsewhere.
Moreover, it's important to remember that such analysis can be performed by third parties who ...
Open source hardware means that the designs and specifications (shape, size, materials, contruction methods) are open source. This could be one or several of various available formats:
HDL source code
integrated circuit layout data
In the case of hardware, open source means that the ...
Your best bet seems to be the a Creative Commons Share Alike license.
Since you are looking for to license a creative work - your diagrams, examples, and words. Right away, Creative Commons should ring a bell.
The CC BY-SA license looks good. Here's why:
It includes a ShareAlike/Copyleft clause
This will require anyone who makes changes to this to release ...
Consulting documentation and using that documentation to create your own work does not mean you are "creating a work based on the documentation."
Let's look at the example you have asked about. The documentation explains how to use the makeStyles function of a component which you have included. The component itself, which has its own code, and its own files,...
Apparently theres this standard/specification/bot:
Here is more info:
And here is a big example:
Open sourcing generally means releasing the format that you designed the hardware in.
For hardware this would be circuit diagrams, trace design, blueprints. Things like that.
If you previously took out a patent on it then you would provide the patent as well along with a license for people to use the patent freely.
The question has been around, but this is what I noticed based on the current situation:
You mention often posed questions. If the same questions are posed more than once they will often at least contain some common keywords (or synonyms). A common search engine should be able to find hits in your documentation (or FAQ) based on the question, e.g. search ...
First off, I will reiterate what others have said: "navigating" is not the verb I think to click on when looking for documentation. It sounds more like you're describing how to read the code that you wrote, compiled, and have posted a webpage about.
You have various things that fall under "documentation":
White papers, general info, and misc guides
How to ...
CC BY-NC-SA has three requirements:
Attribution is very easy to fulfil. ShareAlike is a copyleft-like mechanism but only activates if you perform an adaptation, that is if you modify the work. If you are including code examples verbatim then you aren't adapting.
The real problem is the NC clause. You ...
Are there approaches in the open source community have proven their worth to
provide an easily, for everyone editable documentation
which can simply be shipped as offline copy with a web application
and support some translation feature?
This would be called wikipedia, would it?
Similarly, there is a project called Dokuwiki that might be more appropriate ...