same question applies to the rest of the wiki pages. additional questions:
who uses these?
who should be using these pages, specifically, do we expect stan devs to go looking for answers in the wiki, and if so, what are the questions? there were wiki pages on the Stan developer process - are these complete, correct, etc?
wikis are a challenge to keep up to date, ditto every other form of documentation. my particular concerns are:
what documentation do Stan devs and prospective Stan devs need to help the on-boarding process?
what documentation do Stan users need to help with software installation and troubleshooting?
I don’t know about the rest. I definitely used them when I first started, and some of them have valuable information. Would probably have to go through these manually though to answer those questions.
I really think we should deprecate all the wiki pages for the C++ codebase. We can use the same style that I’ve setup for the stan math site then also have versioned docs
“code review” is linked into the math wiki developer page - Home · stan-dev/math Wiki · GitHub - why just link to a particular subsection of that page - what about the rest of what’s there?
doxygen docs are more compact, true, but otherwise, I don’t see how this solves the problem of identifying what isn’t currently documented but should be, nor does it help keep the docs updated.
That Doxygen thing looks really slick. I’m bookmarking that. Just figured out I can just search for the template magic stuff here and get quick results (require_all_eigen_col_vector_vt vs require_all_eigen_col_vector_t, etc.)
But I guess now I just have +1 piece of documentation lol, so what @mitzimorris said applies too.
what do you mean “same style” - the layout used by doxygen? the Contributors section links into the wiki, e.g.:
Yeah I just mean using doxygen sites instead of the wiki
the Contributors section links into the wiki, e.g.:
Oh my! Those links should be updated / fixed
doxygen docs are more compact, true, but otherwise, I don’t see how this solves the problem of identifying what isn’t currently documented but should be, nor does it help keep the docs updated.
doxygen docs are more compact, true, but otherwise, I don’t see how this solves the problem of identifying what isn’t currently documented but should be, nor does it help keep the docs updated.
Doxygen docs are just, docs! The webpages there are the same as the ones from the wiki site.
I don’t see how this solves the problem of identifying what isn’t currently documented but should be, nor does it help keep the docs updated.
Personally I think attaching docs to the site makes it so docs are more in the review process. So if we add something new we can see whether the docs site is updated in the PR rather than the reviewee having to check the wiki each time to make sure the doc for something is updated. We could also have versions of the docs that coincide with each stan release. For example, eigen has docs for it’s stable version and it’s dev version. Right now we just have math docs for the dev version, but if we abandon the wiki and exclusivly use the doxygen site we can have versioned docs for each release.
Yes I agree! I think ripping the bandaid off and going fully to doxygen / roxygen sites and removing the wikis would be beneficial with keeping docs up to date and making sure things are at least doc’d in the future / filing issues about what’s not doc’d yet. We would/could still have different sites (one for cmdstan, stan, stan math etc). But we could link all of those on the main site
at the code base level, we’re adding functions, classes, refactoring. the developer process docs are about process - how we do things. so I don’t see how a PR that’s changing/adding a function will alert us to the need for a change to the process docs.
the wiki pages have been used to answer questions about what do users need to know - there are wiki pages on “Prior Recommendatiaons”, interface toolchain installation issues.
and there are many wiki pages that are relevant to both users and devs - I was looking for the info on C++ versions for testing purposes.
also, Doxygen is an extremely brittle, perl-based, under-documented system - @stevebronder did a fabulous job upgrading them a while back, but I recall that we had difficulty actually getting them to work correctly. not that I’ve got anything better to suggest.
I think the biggest issue with doxygen is that the docs are dependent on the version installed. If we have a workflow to build them and host them online, it shouldn’t be an issue.
Hmm, this does feel true for a lot of things. Though if we had Compilers and Language Features on the stan-math doc site then I think there’s at least a higher chance that when we make a PR to update jenkinsfile/make we would remember to update the site docs if we start taking the site docs more seriously.
the wiki pages have been used to answer questions about what do users need to know - there are wiki pages on “Prior Recommendatiaons”, interface toolchain installation issues.
Yes I should have emphasized the C++ part of my original statement.
I really think we should deprecate all the wiki pages for the C++ codebase.
Prior recommendations and interfaces are higher up in the stack and they can manage them however they would think is best. We have doxygen setup for the C++ codebases already so idt it would be that hard to standardize all of them to look like stan math.
How many user facing docs are there tho’ in the C++ codebases? I’m v confused by all the wiki pages on stan. How are there 60 pages in the wiki, are people just writing secret notes there?
So I think this would directly benefit from everything being on doxygen sites. The math library should be the one to hold these requirements with everyone else linking to them. So if math changes anything via flags, dependencies, etc. those changes come with new doc pages / info and everyone in the C++ upstream has that voila.
lol yeah it’s not pretty sometimes (all the time) but with some elbow grease it does do it’s job pretty well. The comment docs themselves are also very nice. The site itself worked, it’s mostly that the new site needed a newer version of doxygen so older versions kaputz’d when trying to build the docs locally. Dan has the opposite problem now where a newer version of doxygen catches an error it didn’t catch before! Which is good! But ugh. it would be way too much effort to move over so I think it’s better to just stick with it.
I’d counter that idt it’s underdocumented, I think it’s bad in a few specific but very frustrating ways.
I tried to use the GitHub search function to get a sense of how many wiki pages we have across all repos - somewhere upwards of 147 pages. repo stan wins at 75 pages, followed by math which has 26 page.
on the github home page, in the search box, try these queries:
org:stan-dev in:body c++ - matches 82 wiki pages org:stan-dev in:body cpp - matches 18 pages org:stan-dev in:body the - matched 147 pages
the github search interface is very clunky, ditto the per-repo wiki viewer. is there a way to get the basic stats on all wiki pages in the repo via the GitHub API? it would be useful to get the following: repo, date last updated, title, and URL.
I woudln’t mind self-contained doxygen for the code, but for the dev process, etc., I’d rather stick to the wiki.
I see 75 in the the index. I deleted about 20 of them. I could easily delete another 20 with a couple hours work relocating the content.
I think we should make a single doc for new developers that contains just about everything they should read before getting started. As is, it’s just too hard to collate all the sources.
The designs (like sparse matrices, tuples, etc.) need to move to the design-docs repo.
I removed all the research and marketing stuff and sent copies to @breckbaldwin and @andrewgelman. I also sent a couple direct requests to people to relocate pages I didn’t think the project should manage.