A message from our CEO about the future of Stack Overflow and Stack Exchange. Read now.
42

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 ...


19

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 ...


18

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 ...


12

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 ...


8

"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 ...


6

There is no standard way of listing contributors, but there are some conventions and habits. The GCC compiler has a MAINTAINERS file which could inspire you


6

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 ...


6

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 ...


6

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 ...


5

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 ...


5

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 ...


4

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 ...


4

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....


4

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 ...


4

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 ...


4

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 ...


3

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 ...


3

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 ...


3

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: technical drawings written instructions HDL source code circuit diagrams/schematics integrated circuit layout data In the case of hardware, open source means that the ...


3

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,...


2

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.


2

CC BY-NC-SA has three requirements: Attribution (BY) NonCommercial (NC) ShareAlike (SA) 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 ...


2

You can't. Implementations of a protocol are not considered derived works of the protocol description under copyright law, so the copyright license on the protocol description has no influence at all on the copyrights of the implementations. The closest you can get to your first point is if you have a patent on (a part of) the technology needed to ...


2

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 ...


2

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 ...


2

The man pages of Git are under the same license as Git, e.g. GPL 2.0 (and v2.0 only: this is the same as the Linux kernel license)


2

While re-reading the license again and again, I noticed the slight wording difference that makes it suitable. this software and associated documentation files (the "Software") So when software is spelled with a capitalized "S", it means: software + documentation. And that's the capitalized version that is used in all the rest of the document: rights ...


2

As the output document gets created by an automated process, there is not enough creative work in the creation of that document to make it copyrightable in its own right. The output document can only be licensed under the combination of licenses that cover the documentation source and the code snippets. This means license [3] will be a combination of ...


1

http://pythonhosted.org is owned by the Python Software Foundation. You should contact the sysadmin for Pypi and the PSF to discuss with them if they can setup some redirect to your new doc site. Alternatively or in addition to this, you could setup an HTML meta redirect in your docs: <meta http-equiv="refresh" content="0; url=http://example.com/" />


1

(Note that CC BY-NC-SA 4.0 is not an open source license.) If users contribute (pull requests) to a work (your wiki) licensed under CC BY-NC-SA 4.0, they convey: You can use this contribution under the terms of the license CC BY-NC-SA 4.0. So yes, if you share their contributions, you may not do this in a commercial way. You can only ignore the license ...


Only top voted, non community-wiki answers of a minimum length are eligible