search

qPCR4vir / nana-docs

A Nana offline doxygen dodocumentation project
54 stars 6 forks source link

Wondering if still meaningful to contribute to this wiki. #10

Open leegbestand opened 5 years ago

leegbestand commented 5 years ago

Hi, I was wondering if it is still meaningful to contribute to this area of nana. There are several places for docs for nana, however the last activity on this repo is almost two years ago. So is this still the place for documentation concerning nana, or is there another place?

Xeverous commented 5 years ago

The code itself has last commit in July 2018 but the wiki has edits about a month ago.

qPCR4vir commented 5 years ago

yes, please contribute! I will delete this repo if it will be deprecate, But we want this repo to be updated. See: http://nanapro.org/en-us/forum/index.php?u=/topic/1137/ggdocumenting-nana

Xeverous commented 5 years ago

I don't see the problem in updating it, but I a see problem with docs themselves.

Currently, there are 4 different websites with nana documentation:

Having 4 separate documentations is as dangerous as having 4x duplicated code. These docs already differ a lot. There should be only 1 doc, the only true one. Right now various wikis duplicate and spread mismatched information about the actual library API.

I propose that:

Additionally (my personal opinion):

qPCR4vir commented 5 years ago

hi, I apreciate your opinions, really, but did you read the discusions? -C+D. It is easer to said than to do. You will need to master Doxygen very well to offer properly both high and low level docs in a well structured way. C - is the author opinion about what and why is important, while D is just everything., A is not compareble to B, Maybe you mean https://github.com/qPCR4vir/nana-docs/wiki. Even so: if I see duplicaion I will erase what is in https://github.com/qPCR4vir/nana-docs/wiki and add a link to B. A is the source to D in the same way https://github.com/cnjinhao/nana-handbook is the source of C.

Wiki is hard to work with/contribute to. It is not git-versioned

humm?? I simply cloned it from Guithub and have it under git and commit and push normally. See links botton:

Clone this wiki locally https://github.com/qPCR4vir/nana-docs.wiki.git

Xeverous commented 5 years ago

humm?? I simply cloned it from Guithub and have it under git and commit and push normally. See links

Ok, my fault. Havent't seen it.

You will need to master Doxygen very well to offer properly both high and low level docs in a well structured way.

I don't think so. Not having absolutely all skills is not an excuse to not provide such documentation. C++ aswell is a hard language but no one would prefer non-RAII code just because "it is hard to learn".

Also, the D documentation has a lot of examples and various articles are well separated from the API reference. You have already done a proper structure.

I don't see any value in C because it only provides links to the wiki - 1 is enough, wiki already has a menu. The "Reference Manual" on C is (by my opinion) a strictly worse subset of D.

Even so: if I see duplicaion I will erase what is in https://github.com/qPCR4vir/nana-docs/wiki and add a link to B.

Fine, remove any duplication. The question is why 2 wikis. Moving across them is not convenient and you have to maintain 2 menus. Why do you want to maintain 2 separate wikis? I just don't get it.

qPCR4vir commented 5 years ago

I don't think so. Not having absolutely all skills...

OK. You are invited to improve it. Please first discuss here your ideas before making a big or disruptive PR. Just as always.

the D documentation has a lot of examples

which need a lot of work. Some are copy/pasted in the text but all need to be embedded istead.

I don't see any value in C because...

Well, here we just agree to disagree. To me this is by far the most important documentation. This is the view of the author and nothing beat that. Nobody knows better. Only important things are here. The style and the structure is far better that one can do with a wiki. And to maintain a consistent wiki is a pain. In D many is automated. You may try to update the content on it.

leegbestand commented 5 years ago

When I asked this question I was having the same problem, especially the fragmentation. I also asked this question on the nana repo, which you can find here It gives three places where documentation can be found, which I think is a nice overview.

However as a beginner using nana that information was not available yet. I think it would be clear to have one place(homepage or main wiki?) that will become the main starting point and from there link to the several type of documentation, where every type has a clear goal. Also referencing between wiki's sound very confusing.

The forum link still gives no clear goal for the documentation.

Xeverous commented 5 years ago

I agree completely with @leegbestand.

@qPCR4vir what do you think about merging 2 wikis to 1?

qPCR4vir commented 5 years ago

what do you think about merging 2 wikis to 1?

it is possible. It is just a matter of convenience. While cross-linking is almost transparent for the reader, the convenience of committing and pushing changes for the major author. Or I like to see the repo-traffic for example. Nothing important. Making the entry-point clearer could be my priority.

Xeverous commented 5 years ago

While cross-linking is almost transparent for the reader

It is not transparent. Both wikis have different sidebar menu and moving across 2 wikis at the same time is not convenient.

convenience of committing and pushing changes for the major author

I don't see the problem here. Since wiki is git-versioned, you can easily merge commits and work together on a single project.

qPCR4vir commented 5 years ago

hmm? i will need to check who can push to what fork of the wiki