search

zikichombo / meta

organisation-wide coordination
3 stars 2 forks source link

proposal: unified godoc under zc.org #5

Open wsc1 opened 6 years ago

wsc1 commented 6 years ago

The zc projects don't have a unified view of all of zikichombo.org on godoc.org.

As one major goal of zc is simple, effective inter-op between the projects, it would be nice to host zc godoc in one place under zikichombo.org.

This way, we could also keep better tabs of what is of interest to consumers.

Thoughts?

Have the docs on gddo and zcdo? only zcdo? only gddo?

mewmew commented 6 years ago

The docs should definitely be on GoDoc.org. Perhaps high-level design documentation can live on zc.org, and API docs on gddo?

wsc1 commented 6 years ago

The problems with gddo are

  1. that it doesn't present all the packages in one place. I'm not sure how to make it do that, although upspin.io shows up at godoc.org/upspin.io, so I guess it's possible, just don't know how to do it off hand.

  2. we don't have access to url request statistics for gauging how the documentation is serving those reading it, thus limiting our potential information for improving it. Maybe having it in both places would be a good compromise?

For high level design, so far I've been placing some of it in repo markdown files, which is independent of github (at least in sio) and more for us code monkeys than internauts. I think design documents like golang.org's articles on reflection and other topics would be great on zc.org website for zc specific topics.

mewmew commented 6 years ago

I think they achieve this using a mono repo and a go-imports meta-tag at their web root.

view-source:https://upspin.io/?go-get=1

<meta name="go-import" content="upspin.io git https://upspin.googlesource.com/upspin">

From view-source:http://zikichombo.org/?go-get=1

<!DOCTYPE html>
<html lang='en'>

<head>
  <meta charset='utf-8'>
<meta name='viewport' content='width=device-width, initial-scale=1'>
<meta name='description' content=''>
<meta name='theme-color' content='#dda0dd'>

<meta property='og:title' content='ZikiChombo'>
<meta property='og:description' content=''>
<meta property='og:url' content='http://zikichombo.org/'>
<meta property='og:site_name' content='ZikiChombo'>
<meta property='og:type' content='website'><meta property='og:updated_time' content='2018-08-03T19:26:43&#43;02:00'/><meta name='twitter:card' content='summary'>

<meta name="generator" content="Hugo 0.47-DEV" />

  <title>ZikiChombo</title>
  <link rel='canonical' href='http://zikichombo.org/'>

    <link href="http://zikichombo.org/index.xml" rel="alternate" type="application/rss+xml" title="ZikiChombo" />
...
mewmew commented 6 years ago

For high level design, so far I've been placing some of it in repo markdown files, which is independent of github (at least in sio) I think design documents like golang.org's articles on reflection and what not would be great on zc.org website.

Sounds good.