liguow的个人博客分享 http://blog.sciencenet.cn/u/liguow

博文

how to publish your code (software) in professional fashion?

已有 2727 次阅读 2013-7-10 06:34 |系统分类:科研笔记|关键词:学者| Software, Fashion


Publicizing your software is as important as or even more important than developing your software.
Publish a methodology paper is one way to popularize your tool. However, publication
is necessary but not sufficient to make your tool come out on top among its competitors.

People use your tool either because its outstanding performance or because its more convenient (user friendly) than other tools. How to design algorithm is out of the scope of this blog. Here we are focusing on non-technical part--how to promote your software? or how to convince other people to use your tool ?

1) Find a good name for your software. Try to find a name that is short, unique and easy to pronounce. "short" word is easier to remember. I would suggest to select name with no more than 6 letters, unless you have good reasons to choose a longer one.  "unique" means, when you google the name, links to your software will appear in the first few  entries.  Last but most importantly, the name of your software should be "meaningful", people is able to "guess" its function by the name. Most of times, it's difficult to satisfy all these criteria, but you could brainstorm with your friends and pick the best one.

2) Write good documentation (users manual). Most users will read your documentaion rather than your methodology paper. In the manual, you should tell users where to download your software? How to install it? What prerequisite is required by this software? How to use it? The best practice is to include a walk-through example in you documentation.

Keep in mind: Too many  prerequisites (dependencies) will dissuade people from using your tool.

sphinx is a python program that will help you write a intelligent, beautiful and professional documentation. It was originally designed for python package/program, but C/C++ are also supported very well. Actually, you can use it to prepare customized documentation for any other language. You don't need to know python to use this program. There are 3 simple steps to use sphinx:

First you run "sphinx-quickstart" to setup your project, you will enter a interactive mode, in most cases just hit ENTER to use the default value
Second, you edit the "index.rst" file. The syntax is very simple.
Third, run "make html". You will get your documentation in html format (under _build directory by default).

sphinx will make programmer WANT to write documentation, it's fun!

3) Find a web server is host your and code documentation. sourceforge is by far the best place to host both code and documentation.  Google Code used to be a good alternative, but Google no long supports it in 2014.

Use sourceforge to host you code is very simple:

first register a acount with sourceforge, then create a project, and finally upload your code to sourceforge.

Use sourceforge to host you documentation need a little more work (below example works on both Linux and Mac OS):

(a) open a terminal and run:

ssh-keygen -t rsa

you will get two files under /home/user/.ssh/: id_rsa and id_rsa.pub . Copy everything in id_rsa.pub and paste into sourceforge (/home/account/services, text field with label "SSH keys for Shell/CVS"). After this step you can login to sourceforge without password.

(b) open a terminal and type:

ssh -t wang_xyz,project_abc@shell.sourceforge.net create . (wang_xyz is your registered username with sourceforge, project_abc is the name of project you created)

(c) copy your documentation to sourceforge server with (sftp, scp,... etc)

scp mydoc.html  wang_xyz,project_abc@shell.sourceforge.net:/home/project-web/project_abc/htdocs . (Be sure to replace wang_xyz and project_abs with your actual username and project name)

If you upload a zipped file to sourceforge, you can even login to sourceforge by ssh, then do unzip, cp, rm etc :

ssh -t wang_xyz,project_abc@shell.sourceforge.net

Done! check project_abs.sourceforge.net for your documentation.


Below are 3 examples (documentations were prepared by sphinx and hosted on sourceforge):

http://chipexo.sourceforge.net/

http://rseqc.sourceforge.net/

http://rna-cpat.sourceforge.net/





https://m.sciencenet.cn/blog-986653-706814.html

上一篇:智商和情商
下一篇:香农信息熵 (Shannon's Entropy)在生命科学中的应用

0

该博文允许注册用户评论 请点击登录 评论 (0 个评论)

数据加载中...

Archiver|手机版|科学网 ( 京ICP备07017567号-12 )

GMT+8, 2024-5-29 19:45

Powered by ScienceNet.cn

Copyright © 2007- 中国科学报社

返回顶部